.TH std::basic_streambuf::pbackfail 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::basic_streambuf::pbackfail \- std::basic_streambuf::pbackfail

.SH Synopsis
   protected:
   virtual int_type pbackfail( int_type c = Traits::eof() );

   This function can only be called if any of the following condition is satisfied:

     * gptr() is null,
     * gptr() == eback(), or
     * traits::eq(traits::to_char_type(c), gptr()[-1]) returns false.

   This function is called by the public functions sungetc() and sputbackc() (which, in
   turn, are called by basic_istream::unget and basic_istream::putback) when either:

   1) There is no putback position in the get area (pbackfail() is called with no
   arguments). In this situation, the purpose of pbackfail() is to back up the get area
   by one character, if the associated character sequence allows this (e.g. a
   file-backed streambuf may reload the buffer from a file, starting one character
   earlier).
   2) The caller attempts to putback a different character from the one retrieved
   earlier (pbackfail() is called with the character that needs to be put back). In
   this situation, the purpose of pbackfail() is to place the character c into the get
   area at the position just before basic_streambuf::gptr(), and, if possible, to
   modify the associated character sequence to reflect this change. This may involve
   backing up the get area as in the first variant.

   The default base class version of this function does nothing and returns
   Traits::eof() in all situations. This function is overridden by the derived classes:
   basic_stringbuf::pbackfail, basic_filebuf::pbackfail, strstreambuf::pbackfail, and
   is expected to be overridden by user-defined and third-party library stream classes.

.SH Parameters

   ch - character to put back or Traits::eof() if only back out is requested

.SH Return value

   Traits::eof() in case of failure, some other value to indicate success. The base
   class version always fails.

.SH Example

    This section is incomplete
    Reason: no example

   Defect reports

   The following behavior-changing defect reports were applied retroactively to
   previously published C++ standards.

     DR   Applied to                 Behavior as published                   Correct
                                                                             behavior
                     the calling condition                                 corrected to
   LWG 32 C++98      'traits::eq(*gptr(),traits::to_char_type(c))          match
                     returns false' did not match the description of       the
                     sputbackc()                                           description

.SH See also

             backs out the input sequence to unget a character, not affecting the
   pbackfail associated file
   \fB[virtual]\fP \fI(virtual protected member function of std::basic_filebuf<CharT,Traits>)\fP

   pbackfail puts a character back into the input sequence
   \fB[virtual]\fP \fI\fI(virtual protected member function\fP of\fP
             std::basic_stringbuf<CharT,Traits,Allocator>)
   pbackfail backs out the input sequence to unget a character
   \fB[virtual]\fP \fI(virtual protected member function of std::strstreambuf)\fP
   sungetc   moves the next pointer in the input sequence back by one
             \fI(public member function)\fP
   sputbackc puts one character back in the input sequence
             \fI(public member function)\fP

.SH Category:
     * Todo no example
